test(qa): ledger out-of-repo consumers’ specifiers against the published exports maps - #15717

Part of #15589 — option A only. Option B is filed as a decision card, #15715, and is deliberately not implemented here.

The gap

An exports map is a packaging contract, and inside this monorepo nothing is sealed: every in-repo consumer reaches any file through a relative import, a vitest alias or a paths entry. So the repo could not observe a sealing regression at all — not as an oversight, but by construction. It cost the same event twice: 17.3.0 sealed @objectstack/cli (#13123), and both breaks were found after publish, by the consumer, during an upgrade — cloud's objectos-runtime (#13662) and hotcrm's hook-body harness (#15325).

A fix therefore has to import knowledge from outside the repo. That is what the ledger is.

What this adds

packages/qa/downstream-contract/consumer-specifiers.ledger.json — hand-curated, with a $comment header carrying purpose, an OWNER line (domain:devx), the shrink-only rule, and the entry shape. Three seeded entries, each with specifier / consumer / since / ratifiedBy:

⚠️ hotcrm is the only cited consumer of @objectstack/cli/package.json. #15589 attributes it to cloud as well, and no reading of #13123 / #13662 / #15325 records that, so it is not claimed. An uncited row would make this ledger exactly as trustworthy as the memory it replaces.

test/consumer-specifier-ledger.test.ts holds it against the real maps. Resolving from inside the workspace would prove nothing — this package's own node_modules/@objectstack/cli is a symlink into packages/cli, and tsconfig paths and vitest aliases bypass exports besides. So each ledgered package is packed with pnpm pack, unpacked into a throwaway node_modules outside the workspace, and every specifier is resolved by a child node with nothing of this workspace on its resolution path — createRequire().resolve() for require, import.meta.resolve() for import. Failures name the specifier and the consumer.

It is the technique packages/cli/test/published-subpath-hook-body.pin.test.ts uses (landed with #15611), and the two are deliberately kept separate: that pin asks "does the CLI's map still spell the subpaths this repo ratified", from inside packages/cli. This asks "does every specifier a named out-of-repo consumer imports still resolve". A pin over one package's map cannot see the next package that gains one; the ledger grows a row rather than a file.

The ledger of losses shrank to empty, mid-branch

When this was written, two of the three specifiers did not resolve: ./hook-body and ./package.json were ratified only by PR #15611, then open. A test asserting "every ledgered specifier resolves" would have been permanently red and could not land, and dropping the two entries would have discarded the knowledge. So the red was ledgered: SEALED_TODAY recorded exactly which specifiers this tree did not open, asserted as a set equality so the table could only shrink.

#15611 then landed while this branch was in flight, and the equality did exactly what its header said: merging main turned the suite red naming the two lines to delete. They are deleted. The table is now empty — every ledgered specifier resolves from a packed tarball today.

The empty table is kept, because it and the contract say different things: "every ledgered specifier resolves" is the contract; "the sealed set is exactly empty" is the ratchet — the line an author must edit, past a ⛔, to make a red green by recording a break instead of repairing it.

Non-vacuity — measured, not asserted

Ablation on the final head (a4421eb89), ./console deleted from packages/cli/package.json exports in the worktree, never committed:

• mutation proven on disk before measuring: "./console" occurrences 1 → 0, git diff HEAD --stat non-empty, resulting map printed.
• red, 2 failed / 10 passed, naming the consumer:

SEALED: @objectstack/cli/console no longer resolves under the `require` condition.
      This breaks objectstack-ai/cloud — the `objectos-runtime` node server, which mounts
      the Console SPA through resolveConsolePath / hasConsoleDist / createConsoleStaticPlugin
      ledgered:  2026-08-31 (#13662)
      probe:     {"require":{"ok":false,"code":"ERR_PACKAGE_PATH_NOT_EXPORTED"},...}
      Re-open the subpath in the package's exports map, or migrate the consumer and cite
      that migration in the ledger.

• restore proven by blob hash: git hash-object = 5d0ba78b18fc55d292d161974439b60d7c60bd43 = the HEAD blob, git diff HEAD empty, git status clean.
• re-run after restore: 12 passed.

The probe returning a real ERR_PACKAGE_PATH_NOT_EXPORTED is what establishes the pipeline ran end to end — pack, unpack, real resolver.

The shape checks are load-bearing for the same reason: the ledger must be non-empty, every ledgered package must declare an exports map (an unsealed package resolves anything and proves nothing), every ledgered package must be a declared dependency, and at least one door must open, so a tarball that failed to unpack cannot read as "all sealed, as recorded". A new check also separates two diagnoses the map cannot tell apart on its own: ERR_PACKAGE_PATH_NOT_EXPORTED is a seal; MODULE_NOT_FOUND is a declared door leading nowhere — unbuilt, or files not shipping what exports names.

CI wiring — measured

The suite does run on PR-side CI for a packages/cli/package.json change. Measured with #15611's own diff pinned as the base and head:

TURBO_SCM_BASE=f99dbcc45 TURBO_SCM_HEAD=95d5cbb31 pnpm exec turbo ls --affected
  -> 7 packages, including @objectstack/downstream-contract

The mechanism is the @objectstack/cli devDependency this PR adds: turbo ls @objectstack/downstream-contract lists @objectstack/cli among its dependencies, and at the merge base the package declared only @objectstack/spec, typescript and vitest, so a cli-only diff could not reach it. Layer B is covered by the same edge — @objectstack/downstream-contract#test declares dependsOn: ["^build"] in turbo.json, so its task hash moves with @objectstack/cli#build and a full-list push or merge-queue run cannot replay a stale cached green.

⚠️ Reported honestly: I tried to prove that edge by ablation and both attempts were confounded, so no clean ablation is claimed. Deleting the manifest entry alone left the edge intact (turbo builds the pnpm workspace graph from pnpm-lock.yaml, which still carried it); deleting the lockfile entry too made the lockfile itself a changed global input, and turbo ls --affected folds in uncommitted working-tree changes, which widened the affected set to 10 rather than removing the package. The claim above rests on turbo's own graph listing and the merge-base manifest, not on a mutation.

No changeset: @objectstack/downstream-contract is "private": true, so it publishes nothing. skip-changeset applied via the additive labels endpoint and read back.

⛔ No file outside packages/qa/downstream-contract/** is edited (plus pnpm-lock.yaml, for that package's own new devDependency). packages/cli/**, root package.json, .github/workflows/** and scripts/check-published-files.mjs are untouched — several are held by other open PRs. check:cross-package-test-inputs passes without a new declaration: OK: 27 package(s) read outside themselves, all declared.

Option B, filed with a measurement — #15715

B would refuse a PR that introduces an exports map unless the changeset is at least minor with a BREAKING-style consumer note. Measured over this repo's history on a4421eb89:

A package born with a map seals nobody — there is no published predecessor to deep-import it. So B as worded fires on 51 commits to catch a class that lives in 7, roughly 7:1 against, with the false positives clustered on new-package PRs. That is the substance of #15715, which recommends a born-vs-retrofit discriminator over B as literally worded. (The 69 is independently corroborated by check:published-files: "69 declare an exports map".)

Verification — all on final head a4421eb89

• pnpm --filter '@objectstack/cli...' build — exit 0.
• new suite — exit 0, Test Files 1 passed (1) / Tests 12 passed (12).
• whole qa package — exit 0, Test Files 3 passed (3) / Tests 31 passed (31); typecheck exit 0 (its tsconfig include covers test/**/*, so the new file is in the program).
• derived family, node scripts/pm/dispatch-gates.mjs --changed --commands --repo objectstack-ai/objectstack on this head with no stale-tree warning: 85 commands run, 80 exit 0. Verdict lines quoted rather than bare $?; exit codes captured before any pipe:

check-nul-bytes: OK (scanned 7590 text file(s) ... no raw ASCII control bytes).
✓ check:published-files - 69 publishable package(s) of 79 workspace member(s) ... 69 declare
  an `exports` map gating what of that is resolvable (census control: floor 50).
OK: 27 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.
✓ dispatch-gates self-test: 1445 cases pass.

NOT MEASURED (5) — none of them a red

• check:partof-closing-keyword, check:single-claim-paths — both print NOT WIRED: no PR_BODY / PR_NUMBER locally. Re-run against this PR once it exists.
• check:dual-build-cjs-loads — PREREQUISITE NOT MET … ⛔ This is NOT a pass: nothing was measured (16 packages unbuilt; needs a full pnpm build).
• check:published-readme-exports — same cause, 16 unbuilt packages. Already filed as [finding] check:published-readme-exports reports an unbuilt workspace as 40+ README findings — exit 1 where its sibling exits 3 PREREQUISITE NOT MET #15285 and [finding] check:published-readme-exports answers an UNBUILT workspace closure with exit 1 and 40+ Build first lines — indistinguishable from a real finding, where its sibling check-type-check-coverage models the same precondition as exit 3 PREREQUISITE NOT MET #15600.
• spec check:react-declaration-parity — MANIFEST is not set … This gate did NOT run; needs an objectui build and a browser.

🤖 Generated with Claude Code

https://claude.ai/code/session_012zGPuVVX3deAx9LdjK8jCk

Generated by Claude Code